home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / globber.exe / MATCH.DOC < prev    next >
Encoding:
Text File  |  1991-03-12  |  6.9 KB  |  162 lines
  1.  
  2.                     REGEX Globber (Wild Card Matching)
  3.  
  4.                A *IX SH style pattern matcher written in C
  5.                    V1.10 Dedicated to the Public Domain
  6.  
  7.                                 March  12, 1991
  8.                                  J. Kercheval
  9.                          [72450,3702] -- johnk@wrq.com
  10.  
  11.  
  12.  
  13.  
  14. *IX SH style Regular Expressions
  15. ================================ 
  16.  
  17. The *IX command SH is a working shell similar in feel to the MSDOS
  18. shell COMMAND.COM.  In point of fact much of what we see in our
  19. familiar DOS PROMPT was gleaned from the early UNIX shells available
  20. for many of machines the people involved in the computing arena had
  21. at the time of the development of DOS and it's much maligned
  22. precursor CP/M (although the UNIX shells were and are much more
  23. flexible and powerful then those on the current flock of micro
  24. machines).  The designers of DOS and CP/M did some fairly strange
  25. things with their command processor and OS.  One of those things was
  26. to only selectively adopt the regular expressions allowed within the
  27. *IX shells.  Only '?' and '*' were allowed in filenames and even with
  28. these the '*' was allowed only at the end of a pattern and in fact
  29. when used to specify the filename the '*' did not apply to extension.
  30. This gave rise to the all too common expression "*.*".
  31.  
  32. REGEX Globber is a SH pattern matcher.  This allows such
  33. specifications as *75.zip or * (equivelant to *.* in DOS lingo).
  34. Expressions such as [a-e]*t would fit the name "apple.crt" or
  35. "catspaw.bat" or "elegant".  This allows considerably wider
  36. flexibility in file specification, general parsing or any other
  37. circumstance in which this type of pattern matching is wanted. 
  38.  
  39. A match would mean that the entire string TEXT is used up in matching
  40. the PATTERN and conversely the matched TEXT uses up the entire
  41. PATTERN. 
  42.  
  43. In the specified pattern string:
  44.      `*' matches any sequence of characters (zero or more)
  45.      `?' matches any character
  46.      `\' suppresses syntactic significance of a special character
  47.      [SET] matches any character in the specified set,
  48.      [!SET] or [^SET] matches any character not in the specified set.
  49.  
  50. A set is composed of characters or ranges; a range looks like
  51. 'character hyphen character' (as in 0-9 or A-Z).  [0-9a-zA-Z_] is the
  52. minimal set of characters allowed in the [..] pattern construct.
  53. Other characters are allowed (ie. 8 bit characters) if your system
  54. will support them (it almost certainly will).
  55.  
  56. To suppress the special syntactic significance of any of `[]*?!^-\',
  57. and match the character exactly, precede it with a `\'.
  58.  
  59. To view several examples of good and bad patterns and text see the
  60. output of MATCHTST.BAT
  61.  
  62.  
  63.  
  64. MATCH() and MATCHE()
  65. ====================
  66.  
  67. The match module as written has two parsing routines, one is matche()
  68. and the other is match().  Since match() is a call to matche() which
  69. simply has its output mapped to a BOOLEAN value (ie TRUE if pattern
  70. matches or FALSE otherwise), I will concentrate my explanations here
  71. on matche().
  72.  
  73. The purpose of matche() is to match a pattern against a string of
  74. text (usually a file name or specification).  The match routine has
  75. extensive pattern validity checking built into it as part of the
  76. parser and allows for a robust pattern match.
  77.  
  78. The parser gives an error code on return of type int.  The error code
  79. will be one of the the following defined values (defined in match.h):
  80.  
  81.     MATCH_PATTERN  - bad pattern or misformed pattern
  82.     MATCH_LITERAL  - match failed on character match (standard
  83.                      character)
  84.     MATCH_RANGE    - match failure on character range ([..] construct)
  85.     MATCH_ABORT    - premature end of text string (pattern longer
  86.                      than text string)
  87.     MATCH_END      - premature end of pattern string (text longer
  88.                      than pattern called for)
  89.     MATCH_VALID    - valid match using pattern
  90.  
  91. The functions are declared as follows:
  92.  
  93.     BOOLEAN match (char *pattern, char *text);
  94.  
  95.     int     matche(register char *pattern, register char *text);
  96.  
  97.  
  98.  
  99. IS_VALID_PATTERN() and IS_PATTERN()
  100. ===================================
  101.  
  102. There are two routines for determining properties of a pattern
  103. string.  The first, is_pattern(), is designed simply to determine if
  104. some character exists within the text which is consistent with a SH
  105. regular expression (this function returns TRUE if so and FALSE if
  106. not).  The second, is_valid_pattern() is designed to check the
  107. validity of a given pattern string (TRUE return if valid, FALSE if
  108. not).  By 'validity', I mean well formed or syntactically correct.
  109.  
  110. In addition, is_valid_pattern() has as one of it's parameters a
  111. return code for determining the type of error found in the pattern if
  112. one exists.  The error codes are as follows and defined in match.h:
  113.  
  114.     PATTERN_VALID - pattern is well formed
  115.     PATTERN_ESC   - pattern has invalid literal escape ('\' at end of
  116.                     pattern)
  117.     PATTERN_RANGE - [..] construct has a no end range in a '-' pair
  118.                     (ie [a-])
  119.     PATTERN_CLOSE - [..] construct has no end bracket (ie [abc-g )
  120.     PATTERN_EMPTY - [..] construct is empty (ie [])
  121.  
  122. The functions are declared as follows:
  123.  
  124.     BOOLEAN is_valid_pattern (char *pattern, int *error_type);
  125.  
  126.     BOOLEAN is_pattern (char *pattern);
  127.  
  128.          ----------------end-of-author's-documentation---------------
  129.  
  130.                         Software Library Information:
  131.  
  132.                    This disk copy provided as a service of
  133.  
  134.                         The Public (Software) Library
  135.  
  136.          We are not the authors of this program, nor are we associated
  137.          with the author in any way other than as a distributor of the
  138.          program in accordance with the author's terms of distribution.
  139.  
  140.          Please direct shareware payments and specific questions about
  141.          this program to the author of the program, whose name appears
  142.          elsewhere in  this documentation. If you have trouble getting
  143.          in touch with the author,  we will do whatever we can to help
  144.          you with your questions. All programs have been tested and do
  145.          run.  To report problems,  please use the form that is in the
  146.          file PROBLEM.DOC on many of our disks or in other written for-
  147.          mat with screen printouts, if possible.  The P(s)L cannot de-
  148.          bug programs over the telephone.
  149.  
  150.          Disks in the P(s)L are updated monthly, so if you did not get
  151.          this disk  directly from the P(s)L,  you should be aware that
  152.          the files in this set may no  longer be the current versions.
  153.  
  154.          For a copy of the latest monthly software library newsletter
  155.          and a list of the 2,000+ disks in the library, call or write
  156.  
  157.                         The Public (Software) Library
  158.                               P.O.Box 35705
  159.                            Houston, TX 77235-5705
  160.                                (713) 524-6394
  161.  
  162.